Graphics Plus

home *** CD-ROM | disk | FTP | other *** search

/ Graphics Plus / Graphics Plus.iso / amiga / gui / mui / mui14-dv.lha / MUI / Developer / Autodocs / MUI_Area.doc < prev next >

Wrap

Text File | 1993-10-28 | 20.0 KB | 802 lines

TABLE OF CONTENTS Area.mui/Area.mui Area.mui/MUIA_ApplicationObject Area.mui/MUIA_Background Area.mui/MUIA_BottomEdge Area.mui/MUIA_ControlChar Area.mui/MUIA_Disabled Area.mui/MUIA_ExportID Area.mui/MUIA_FixHeight Area.mui/MUIA_FixHeightTxt Area.mui/MUIA_FixWidth Area.mui/MUIA_FixWidthTxt Area.mui/MUIA_Font Area.mui/MUIA_Frame Area.mui/MUIA_FramePhantomHoriz Area.mui/MUIA_FrameTitle Area.mui/MUIA_Height Area.mui/MUIA_HorizWeight Area.mui/MUIA_InnerBottom Area.mui/MUIA_InnerLeft Area.mui/MUIA_InnerRight Area.mui/MUIA_InnerTop Area.mui/MUIA_InputMode Area.mui/MUIA_LeftEdge Area.mui/MUIA_Pressed Area.mui/MUIA_RightEdge Area.mui/MUIA_Selected Area.mui/MUIA_ShowSelState Area.mui/MUIA_Timer Area.mui/MUIA_TopEdge Area.mui/MUIA_VertWeight Area.mui/MUIA_Weight Area.mui/MUIA_Width Area.mui/MUIA_Window Area.mui/MUIA_WindowObject Area.mui/Area.mui Area class is a super class for every other MUI class except windows and applications. It holds information about an objects current position, size and weight and manages frames, fonts and backgrounds. Additionally, area class handles the user input. By setting an objects MUIA_InputMode, you can make it behave like a button or like a toggle gadget. That's why MUI doesn't offer an extra button class. A button is simply a text object with a raised frame and a relverify input mode. Since especially group class is a subclass of area, you can create rather complex buttons consisting of many other display elements. Area.mui/MUIA_ApplicationObject NAME MUIA_ApplicationObject -- [..G], Object * FUNCTION You can obtain a pointer to the application object that some gadget belongs to by using this attribute. Useful mainly within callback hooks if you do not want to deal with global variables. SEE ALSO MUIA_WindowObject Area.mui/MUIA_Background NAME MUIA_Background -- [IS.], LONG FUNCTION Adjust the background for an object. Every MUI object has its own background setting. The background is displayed "behind" the actual object contents, e.g. behind a the text of a text object or behind the image of an image object. This attribute takes the same values as MUIA_Image_Spec, please refer to autodocs of image class for a complete description. An object without a specific background setting will inherit the pattern from its parent group. The default background for a window and many other background patterns are adjustable with the preferences program. Only a few MUII_xxxxxxx tags make sense as background. Important are: MUII_ButtonBack: You have to set this when you create a button gadget. Thus, your button will be displayed in the users preferred style. MUII_TextBack: Set this when you create a text object with a TextFrame, e.g. some kind of status line. Do *not* use MUII_TextBack for simple text without frame (e.g. gadget labels). MUII_BACKGROUND MUII_SHADOW MUII_SHINE MUII_FILL MUII_SHADOWBACK MUII_SHADOWFILL MUII_SHADOWSHINE MUII_FILLBACK MUII_FILLSHINE MUII_SHINEBACK MUII_SHINEBACK2: One of MUI's predefined pattern. These are not configurable by the user and will always look the same. Note: It is *important* that you test your programs with a fancy pattern configuration. With the default setting you won't notice any errors in your backgrounds. Area.mui/MUIA_BottomEdge NAME MUIA_BottomEdge -- [..G], LONG FUNCTION You can use this to read the current position and dimension of an object, if you e.g. need it to pop up some requester below. Of course, this attribute is only valid when the parent window of the object is currently open. SEE ALSO MUIA_TopEdge, MUIA_Width, MUIA_Height, MUIA_RightEdge, MUIA_LeftEdge Area.mui/MUIA_ControlChar NAME MUIA_ControlChar -- [I..], char FUNCTION Pressing the control char will have the same effect as pressing return if the object was active. This can be used to create old style key shortcuts. Note: Using an uppercase control char will force the user to press shift. SEE ALSO mui.h / KeyButton() macro Area.mui/MUIA_Disabled NAME MUIA_Disabled -- [ISG], BOOL FUNCTION Disable or enable a gadget. Setting this attribute causes a gadget to become disabled, it gets a ghost pattern and doesn't respond to user input any longer. Disabled gadgets cannot be activated with the TAB key. Using MUIA_Disable on a group of objects will disable all objects within that group. EXAMPLE /* we have a radio button gadget with three */ /* entries, the third should enable a string gadget */ /* with additional parameters */ DoMethod(radio, MUIM_Notify, MUIA_Radio_Active, 0, string, 3, MUIM_Set, MUIA_Disabled, TRUE); DoMethod(radio, MUIM_Notify, MUIA_Radio_Active, 1, string, 3, MUIM_Set, MUIA_Disabled, TRUE); DoMethod(radio, MUIM_Notify, MUIA_Radio_Active, 2, string, 3, MUIM_Set, MUIA_Disabled, FALSE); Area.mui/MUIA_ExportID NAME MUIA_ExportID -- [ISG], LONG FUNCTION Objects with a non NULL MUIA_ExportID export their contents during MUIM_Application_Save and import them during MUIM_Application_Load. You have to use different ExportIDs for your objects! SEE ALSO MUIM_Application_Save, MUIM_Application_Load Area.mui/MUIA_FixHeight NAME MUIA_FixHeight -- [I..], LONG FUNCTION Give your object a fixed pixel height. This tag is absolutely not needed in a general MUI application and only present for emergency situations. Please think twice before using it! EXAMPLE /* create an 8x8 pixel rectangle with FILLPEN */ RectangleObject, MUIA_FixWidth , 8, MUIA_FixHeight , 8, MUIA_Background, MUII_FILL, End; SEE ALSO MUIA_FixWidth, MUIA_FixWidthTxt, MUIA_FixHeightTxt Area.mui/MUIA_FixHeightTxt NAME MUIA_FixHeightTxt -- [I..], LONG FUNCTION Give your object a fixed pixel height. The height will match the height of the given string. This tag is absolutely not needed in a general MUI application and only present for emergency situations. Please think twice before using it! EXAMPLE /* create a fixed size rectangle with FILLPEN */ RectangleObject, MUIA_FixWidthTxt , "00:00:00", MUIA_FixHeightTxt, "\n\n", MUIA_Background , MUII_FILL, End; SEE ALSO MUIA_FixHeight, MUIA_FixWidth, MUIA_FixWidthTxt Area.mui/MUIA_FixWidth NAME MUIA_FixWidth -- [I..], LONG FUNCTION Give your object a fixed pixel width. This tag is absolutely not needed in a general MUI application and only present for emergency situations. Please think twice before using it! EXAMPLE /* create an 8x8 pixel rectangle with FILLPEN */ RectangleObject, MUIA_FixWidth , 8, MUIA_FixHeight , 8, MUIA_Background, MUII_FILL, End; SEE ALSO MUIA_FixHeight, MUIA_FixWidthTxt, MUIA_FixHeightTxt Area.mui/MUIA_FixWidthTxt NAME MUIA_FixWidthTxt -- [I..], STRPTR FUNCTION Give your object a fixed pixel width. The width will match the width of the given string. This tag is absolutely not needed in a general MUI application and only present for emergency situations. Please think twice before using it! EXAMPLE /* create a fixed size rectangle with FILLPEN */ RectangleObject, MUIA_FixWidthTxt , "00:00:00", MUIA_FixHeightTxt, "\n\n", MUIA_Background , MUII_FILL, End; SEE ALSO MUIA_FixHeight, MUIA_FixWidth, MUIA_FixHeightTxt Area.mui/MUIA_Font NAME MUIA_Font -- [I.G], struct TextFont * SPECIAL INPUTS MUIV_Font_Inherit MUIV_Font_Normal MUIV_Font_List MUIV_Font_Tiny MUIV_Font_Fixed MUIV_Font_Title FUNCTION Every MUI object can have its own font, just set it with this tag. Objects without an explicit font setting will inherit it from their parent group. You normally won't need to open a font yourself, just use one of the predefined values to get a font from the users preferences. EXAMPLE /* since the text contains tabs, */ /* use the fixed width font for displaying */ msgread = FloattextObject, MUIA_Font, MUIV_Font_Fixed, ..., End; Area.mui/MUIA_Frame NAME MUIA_Frame -- [I..], LONG SPECIAL INPUTS MUIV_Frame_None MUIV_Frame_Button MUIV_Frame_ImageButton MUIV_Frame_Text MUIV_Frame_String MUIV_Frame_ReadList MUIV_Frame_InputList MUIV_Frame_Prop MUIV_Frame_Gauge MUIV_Frame_Group MUIV_Frame_PopUp MUIV_Frame_Virtual MUIV_Frame_Count FUNCTION Define a frame for the current object. Since area class is a superclass for all elements in a window, you can assign frames to every object you wish. You don't adjust the style of your frame directly, instead you only specify a type: MUIV_Frame_Button for standard buttons with text in it. MUIV_Frame_ImageButton for small buttons with images, e.g. the arrows of a scrollbar. MUIV_Frame_Text for a text field, e.g. a status line display. MUIV_Frame_String for a string gadget. MUIV_Frame_ReadList for a read only list. MUIV_Frame_InputList for a list that handles input (has a cursor). MUIV_Frame_Prop for proportional gadgets. MUIV_Frame_Group for groups. How the frame is going to look is adjustable via the preferences program. Four spacing values belong to each frame that tell MUI how many pixels should be left free between the frame and its contents. These spacing values are also user adjustable as long as you don't override them with one of the MUIA_InnerXXXX tags. Note: The first object in a window (MUIA_Window_RootObject) may *not* have a frame. If you need this you will have to create a dummy group with just one child. EXAMPLE strobj = StringObject, MUIA_Frame, MUIV_Frame_String, End; SEE ALSO MUIA_InnerLeft, MUIA_InnerRight, MUIA_InnerTop, MUIA_InnerBottom Area.mui/MUIA_FramePhantomHoriz NAME MUIA_FramePhantomHoriz -- [I..], BOOL FUNCTION Setting this to TRUE causes the specified frame to be a horizontal phantom frame. The frame will not appear but his vertical components (frame height, inner top and inner bottom spacing) will be used to calculate positions and dimensions (horizontal components are treated as 0). This is extremely useful for a correct labeling of objects. You would e.g. label a string gadget by using a text object with a phantom string frame. Thus, the label text will be always on the same vertical position as the string gadget text, no matter what spacing values the user configured. SEE ALSO Label() macros in "mui.h". Area.mui/MUIA_FrameTitle NAME MUIA_FrameTitle -- [I..], STRPTR FUNCTION This tag identifies a text string that will be displayed centered in the top line of a frame. This can become handy if you want to name groups of objects. You may not use MUIA_FrameTitle without defining a MUIA_Frame. EXAMPLE VGroup, MUIA_Frame , MUIV_Frame_Group, MUIA_FrameTitle, "Spacing", ... SEE ALSO MUIA_Frame Area.mui/MUIA_Height NAME MUIA_Height -- [..G], LONG FUNCTION You can use this to read the current position and dimension of an object, if you e.g. need it to pop up some requester below. Of course, this attribute is only valid when the parent window of the object is currently open. SEE ALSO MUIA_TopEdge, MUIA_Width, MUIA_LeftEdge, MUIA_RightEdge, MUIA_BottomEdge Area.mui/MUIA_HorizWeight NAME MUIA_HorizWeight -- [I..], LONG FUNCTION Adjust the horizontal weight of an object. Usually you can simply use MUIA_Weight instead of this tag but in some two-dimensional groups it may become handy to have different horizontal and vertical weights. SEE ALSO MUIA_Weight Area.mui/MUIA_InnerBottom NAME MUIA_InnerBottom -- [I..], LONG FUNCTION Adjust the space between an object and its frame. Usually you shouldn't use this tag since you will override the users preferred default setting. SEE ALSO MUIA_Frame Area.mui/MUIA_InnerLeft NAME MUIA_InnerLeft -- [I..], LONG FUNCTION Adjust the space between an object and its frame. Usually you shouldn't use this tag since you will override the users preferred default setting. SEE ALSO MUIA_Frame Area.mui/MUIA_InnerRight NAME MUIA_InnerRight -- [I..], LONG FUNCTION Adjust the space between an object and its frame. Usually you shouldn't use this tag since you will override the users preferred default setting. SEE ALSO MUIA_Frame Area.mui/MUIA_InnerTop NAME MUIA_InnerTop -- [I..], LONG FUNCTION Adjust the space between an object and its frame. Usually you shouldn't use this tag since you will override the users preferred default setting. SEE ALSO MUIA_Frame Area.mui/MUIA_InputMode NAME MUIA_InputMode -- [I..], LONG SPECIAL INPUTS MUIV_InputMode_None MUIV_InputMode_RelVerify MUIV_InputMode_Immediate MUIV_InputMode_Toggle FUNCTION Adjust the input mode for an object. MUI has no distinct button class. Instead you can make every object (even groups) behave like a button by setting an input mode for them. Several input modes area available: MUIV_InputMode_None: No input, this is not a gadget. MUIV_InputMode_RelVerify: For buttons and similar stuff. MUIV_InputMode_Immediate: Used e.g. in a radio button object. MUIV_InputMode_ToggleSelect: For things like checkmark gadgets. The input mode setting determines how a user action will trigger the attributes MUIA_Selected, MUIA_Pressed and MUIA_Timer. See their documentation for details. EXAMPLE /* A traditional button, just a text object with */ /* a button frame and a relverify input mode: */ okbutton = TextObject, MUIA_Frame , MUIV_Frame_Button, MUIA_InputMode , MUIV_InputMode_RelVerify, MUIA_Text_Contents, "OK", ... SEE ALSO MUIA_Selected, MUIA_Timer, MUIA_Pressed Area.mui/MUIA_LeftEdge NAME MUIA_LeftEdge -- [..G], LONG FUNCTION You can use this to read the current position and dimension of an object, if you e.g. need it to pop up some requester below. Of course, this attribute is only valid when the parent window of the object is currently open. SEE ALSO MUIA_TopEdge, MUIA_Width, MUIA_Height, MUIA_RightEdge, MUIA_BottomEdge Area.mui/MUIA_Pressed NAME MUIA_Pressed -- [..G], BOOL FUNCTION Learn if a button is pressed (or released). The MUIA_Pressed attribute of a gadget is triggered by some user action, depending on the input mode: MUIV_InputMode_RelVerify: - set when lmb is pressed. - cleared when lmb is released and the mouse is still over the gadget (otherwise it will be cleared too, but without triggering a notification event). MUIV_InputMode_Immediate: - undefined, use MUIA_Selected for this. MUIV_InputMode_Toggle: - undefined, use MUIA_Selected for this. Waiting for MUIA_Pressed getting FALSE is the usual way to react on button gadgets. EXAMPLE DoMethod(btcancel,MUIM_Notify,MUIA_Pressed,FALSE, app,2,MUIM_Application_ReturnID,ID_CANCEL); SEE ALSO MUIA_Selected, MUIA_Timer, MUIA_ShowSelState, MUIA_InputMode Area.mui/MUIA_RightEdge NAME MUIA_RightEdge -- [..G], LONG FUNCTION You can use this to read the current position and dimension of an object, if you e.g. need it to pop up some requester below. Of course, this attribute is only valid when the parent window of the object is currently open. SEE ALSO MUIA_TopEdge, MUIA_Width, MUIA_Height, MUIA_LeftEdge, MUIA_BottomEdge Area.mui/MUIA_Selected NAME MUIA_Selected -- [ISG], BOOL FUNCTION Get and set the selected state of a gadget. This attribute can be triggered by the user clicking on the gadget (or using the keyboard), depending on the input mode: MUIV_InputMode_RelVerify: - set when lmb is pressed. - cleared when lmb is released. - cleared when the gadget is selected and the mouse leaves the gadget box. - set when the mouse reenters the gadget box. MUIV_InputMode_Immediate: - set when lmb is pressed. MUIV_InputMode_Toggle: - toggled when lmb is pressed. Of course you may set this attribute yourself, e.g. to adjust the state of a checkmark gadget. A selected gadget will display its border reverse and get the configured MUII_SelectedBack background. This can be avoided using the MUIA_ShowSelState tag. SEE ALSO MUIA_Pressed, MUIA_Timer, MUIA_ShowSelState, MUIA_InputMode Area.mui/MUIA_ShowSelState NAME MUIA_ShowSelState -- [I..], BOOL FUNCTION Normally a gadget will reverse its frame and display the configured MUII_SelectetBack background pattern in its selected state. For some objects (e.g. checkmarks) this is not recommended and can be supressed by setting MUIA_ShowSelState to FALSE. SEE ALSO MUIA_Selected Area.mui/MUIA_Timer NAME MUIA_Timer -- [..G], LONG FUNCTION MUIA_Timer gets triggered when a relverify button is pressed and (after a little delay) increases every INTUITICK as long as the mouse remains over the gadget. This makes it possible to have buttons repeatedly cause some actions, just like the arrow gadgets of a scrollbar. EXAMPLE DoMethod(btmore,MUIM_Notify,MUIA_Timer,MUIV_EveryTime, app,2,MUIM_Application_ReturnID,ID_MORE); DoMethod(btless,MUIM_Notify,MUIA_Timer,MUIV_EveryTime, app,2,MUIM_Application_ReturnID,ID_LESS); SEE ALSO MUIA_Pressed, MUIA_Selected Area.mui/MUIA_TopEdge NAME MUIA_TopEdge -- [..G], LONG FUNCTION You can use this to read the current position and dimension of an object, if you e.g. need it to pop up some requester below. Of course, this attribute is only valid when the parent window of the object is currently open. SEE ALSO MUIA_LeftEdge, MUIA_Width, MUIA_Height, MUIA_RightEdge, MUIA_BottomEdge Area.mui/MUIA_VertWeight NAME MUIA_VertWeight -- [I..], LONG FUNCTION Adjust the vertical weight of an object. Usually you can simply use MUIA_Weight instead of this tag but in some two-dimensional groups it may become handy to have different horizontal and vertical weights. SEE ALSO MUIA_Weight Area.mui/MUIA_Weight NAME MUIA_Weight -- [I..], LONG FUNCTION This tag is a shorthand for MUIA_HorizWeight and MUIA_VertHeight, it sets both weights at once. The weight of an object determines how many room it will get during the layout process. Imagine you have a 100 pixel wide horizontal group with two string gadgets. Usually, each gadget will get half of the room and be 50 pixels wide. If you feel the left gadget is more important and should be bigger, you can give it a weight of 200 (and 100 for the right gadget). Because the left gadget is twice as "heavy" as the right gadget, it will become twice as big (about 66 pixel) as the right one (34 pixel). Of course giving weights only makes sense if the object is resizable. A MUIA_VertWeight for a (always fixed height) string gadget is useless. An object with a weight of 0 will always stay at its minimum size. By default, all objects have a weight of 100. EXAMPLE HGroup, StringGadget, MUIA_Weight, 50, End, StringGadget, MUIA_Weight, 100, End, StringGadget, MUIA_Weight, 200, End, End; SEE ALSO MUIA_HorizWeight, MUIA_VertWeight Area.mui/MUIA_Width NAME MUIA_Width -- [..G], LONG FUNCTION You can use this to read the current position and dimension of an object, if you e.g. need it to pop up some requester below. Of course, this attribute is only valid when the parent window of the object is currently open. SEE ALSO MUIA_TopEdge, MUIA_LeftEdge, MUIA_Height, MUIA_RightEdge, MUIA_BottomEdge Area.mui/MUIA_Window NAME MUIA_Window -- [..G], struct Window * FUNCTION This attribute can be used to get a pointer to the intuition window structure of the parent window ot the object. This pointer could e.g. be used in calls to asl.library. The result is only valid when the window is opened. SEE ALSO MUIA_Window_Window Area.mui/MUIA_WindowObject NAME MUIA_WindowObject -- [..G], Object * FUNCTION You can obtain a pointer to the window object that some gadget belongs to by using this attribute. Useful mainly within callback hooks if you do not want to deal with global variables. SEE ALSO MUIA_ApplicationObject